home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / c / c2man-2.0pl33.lha / c2man-2.0 / C++autodoc next >
Encoding:
Internet Message Format  |  1995-01-24  |  10.8 KB
  1. From greyham Thu Oct 28 18:42:35 1993
  2. Newsgroups: comp.lang.c++,comp.programming.literate
  3. Subject: An Automatic C++ documentation compilation project.
  4. Summary: Anyone willing to add C++ support to c2man?
  5. Keywords: c2man, C, C++, Literate Programming, Documentation
  6.  
  7. Copyright 1993, 1994 by Graham Stoney.
  8. This may be freely redistributed or quoted, so long as it's attributed to me.
  9.  
  10. Writing and maintaining documentation has often been a thorn in the side of the
  11. Software Engineer and Programmer. After spending a great deal of time and
  12. effort writing documentation about a program or software system, the code
  13. invariably changes, quickly rendering the documentation out of date. The
  14. documentation becomes misleading, gets neglected, and quickly becomes useless.
  15.  
  16. "Literate Programming" is one approach to solving this problem. It effectively
  17. introduces a whole new (typesetting) language, requires a quite radical shift
  18. on the part of the "non-literate" programmer and still requires a good deal of
  19. effort on the part of the programmer[1].
  20.  
  21. I'd like to suggest a different approach which lies considerably closer to
  22. more traditional programming practices, and can offer quite immediate benefits
  23. when functional interface documentation is the main documentation required.
  24.  
  25. The primary philosophy here is to use the programming language as far as
  26. possible to express the programmer's intentions, and to use comments only when
  27. the programming language is not sufficiently expressive. A comment can then
  28. become part of the language grammar which is recognised by a "documentation
  29. compiler". This tool parses a superset of the programming language and can
  30. automatically generate documentation in human-readable form by associating the
  31. programmer's comments with the objects in the code by their context.
  32.  
  33. Whilst the idea of extracting documentation from comments in source code is by
  34. no means new, the difference here is that the comments actually form part of
  35. the grammar of the language recognised by the documentation compiler[2].
  36.  
  37. Comments should not repeat information that is already represented in the
  38. program code; for instance, a comment describing a function argument should not
  39. repeat the name and type of that argument (since that information has already
  40. been included, for the compiler), but should appear near the argument.
  41.  
  42. For example, in C, the programmer should write this:
  43.  
  44.     /* include an example in the article */
  45.     enum Result example(int page    /* page it appears on */);
  46.  
  47. Rather than this:
  48.  
  49.     /* include an example in the article
  50.      *
  51.      * PARAMETERS:
  52.      *    int page    page it appears on
  53.      *
  54.      * RETURNS:
  55.      *    RESULT_YES        The readers agreed
  56.      *    RESULT_NO        The readers disagreed
  57.      *    RESULT_YOURE_JOKING    The readers disagreed strongly
  58.      *    RESULT_BLANK_LOOKS    The readers didn't understand
  59.      */
  60.     enum Result example(int page);
  61.  
  62.  
  63. Also in this example, the documentation compiler knows the possible enumerated
  64. values that the function can return (as does the "real" compiler), so it is
  65. unnecessary for the programmer to restate them. The comments need simply be
  66. included in the definition for "enum Result" for the "RETURNS" information to
  67. be generated automatically:
  68.  
  69.     enum Result {
  70.     RESULT_YES,        /* The readers agreed */
  71.     RESULT_NO,        /* The readers disagreed */
  72.     RESULT_YOURE_JOKING,    /* The readers disagreed strongly */
  73.     RESULT_BLANK_LOOKS    /* The readers didn't understand */
  74.     };
  75.  
  76. Critics have suggested that the latter style in the example is easier to read
  77. for someone wishing to call the function in question. Of course, this is a
  78. style question which depends on each person's tastes; but the criticism is tied
  79. to the notion that the source code needs to look "beautiful" because it is the
  80. primary reference for someone wishing to use that function. This becomes much
  81. less significant once documentation is available which is known to _always_ be
  82. up to date. Of course, the latter style takes longer to write and maintain,
  83. and can become out of date should the name or type of the parameter be
  84. changed, yet the comment get neglected.
  85.  
  86. I have implemented one such documentation compiler for the C language called
  87. "c2man", which is freely available[3]. The response from users has been
  88. extremely encouraging; I suspect this is partly because of the wide variety of
  89. styles of comment placement that are recognised: it often correctly recognises
  90. comments that weren't written with c2man in mind at all. While it's use is
  91. focused solely on functional interface documentation and it doesn't have
  92. anywhere near the power of a full Literate Programming system, the focus is on
  93. reducing the effort required by the programmer to the absolute minimum, and
  94. seeing how much documentation we can get essentially "for free".
  95.  
  96. Many people have requested C++ support be added to c2man, and I suspect that
  97. this philosophy would be even more suitable and powerful for documenting
  98. interfaces to C++ classes automatically.
  99.  
  100. Here is an example of how I envisage this philosophy would work when applied to
  101. C++. It's interesting to note that this code was written a couple of years ago
  102. exactly as you see it here, without the idea of generating documentation from
  103. it in mind at all:
  104.  
  105.  
  106.     // generic Timer class
  107.     class Timer
  108.     {
  109.     private:
  110.     static int numactive;    // number of constructed timers.
  111.     static Timer *first;    // first one in list.
  112.     Timer *next;        // next one in linked list.
  113.     Time ticksdiff;        // ticks we take to expire once at front.
  114.  
  115.     enum
  116.     {
  117.         INACTIVE,    // timer is not in chain.
  118.         STARTED,    // one-shot
  119.         RUNNING        // continuous.
  120.     } state;
  121.  
  122.     // original interrupt vector value.
  123.     static void interrupt (far *old_vector)(...);
  124.  
  125.     void (*timeout_function)(int);    // function called when we time out
  126.     int timeout_parameter;        // gets passed to timeout_function
  127.     Time duration;            // timer length (ticks)
  128.  
  129.     static void interrupt far tick(...);    // clock tick routine.
  130.  
  131.     void insert();    // add into active chain.
  132.     void remove();    // remove from active chain.
  133.     void set(Time milliseconds);    // set duration from ms.
  134.  
  135.     public:
  136.     // constructor
  137.     Timer(Time time=0,        // milliseconds
  138.           void (*function)(int)=0,    // called at timeout
  139.           int param=-1);        // param for function
  140.  
  141.     // destructor
  142.     ~Timer();
  143.  
  144.     // start (or restart) a timer running.
  145.     void Start();
  146.     void Start(Time duration);    // how long to run for
  147.  
  148.     // start a timer running continuous.
  149.     void Run();
  150.  
  151.     // stop a timer.
  152.     void Stop();
  153.  
  154.     // is a timer active?
  155.     boolean Active() const { return state != INACTIVE; };
  156.     };
  157.  
  158.  
  159. Processing this class declaration could generate the following automatically:
  160.  
  161.     NAME
  162.         Timer - generic timer class
  163.     
  164.     SYNOPSIS
  165.         class Timer
  166.         {
  167.         public:
  168.             Timer(Time time=0,
  169.                 void (*function)(int)=0,
  170.                 int param=-1);
  171.             ~Timer();
  172.             void Start();
  173.             void Start(Time duration);
  174.             void Run();
  175.             void Stop();
  176.             boolean Active() const;
  177.         };
  178.     
  179.     PARAMETERS
  180.     Time time
  181.         Milliseconds
  182.     
  183.     void (*function)(int)
  184.         called at timeout.
  185.     
  186.     int param
  187.         Param for function.
  188.     
  189.     Time duration
  190.         How long to run for.
  191.     
  192.     DESCRIPTION
  193.     Timer
  194.         Constructor
  195.     
  196.     ~Timer
  197.         Destructor
  198.     
  199.     Start
  200.         Start (or restart) a timer running.
  201.     
  202.     Run
  203.         Start a timer running continuous.
  204.     
  205.     Stop
  206.         Stop a timer.
  207.     
  208.     Active
  209.         Is a timer active?.
  210.  
  211.  
  212. It should also be possible to extract this information from the implementation
  213. of the class (rather than the declaration), if that's where the user prefers to
  214. put the comments describing each member function and their parameters.
  215.  
  216. The ideal tool should:
  217. 1. Avoid imposing a style on the programmer.
  218. 2. Work out section names (NAME, SYNOPSIS etc) without the programmer having
  219.    to specify them explicitly.
  220. 3. Handle C++ and C style code equally well.
  221. 4. Not require the programmer to restate information which is already expressed
  222.    in the syntax of the programming language.
  223. 5. Work reasonably well with existing code.
  224. 6. Flatten the class hierarchy so that the documentation for each class
  225.    includes virtually everything the user needs to know about it.
  226.  
  227. A number of tools already exist which attempt to tackle this problem, such as
  228. class2man, genman, classdoc and docclass.  They vary in sophistication,
  229. utility, and the demands they place on the programmer; however, none as yet
  230. meet all the criteria set out above, and no one tool will suit the tastes of
  231. all programmers.
  232.  
  233. Pouring lots of effort into a really ``smart'' documentation generator makes
  234. sense because once it's done, you get a payback for every document you
  235. generate. Every little feature added to the documentation generator to make
  236. things easier for the programmer pays off multiple times, and minimising the
  237. effort required by the programmer is the key.
  238.  
  239. The logical starting point would be to graft Jim Roskind's C++ grammar[4] into
  240. c2man, modifying it to recognise comments in the relevant places, and adding
  241. all the necessary structures to hold the information from the parser that will
  242. get included in the output.  Very little functional change should be needed in
  243. the lexer, which already recognises C++ comments.
  244.  
  245. Unfortunately, at present I do not have sufficient spare time to make the
  246. additions to c2man required to support C++. It would be a great contribution to
  247. the C++ community, not to mention the documentation time saved by themselves,
  248. for someone involved in C++ work to add this support and release the result[5].
  249.  
  250. If you work with a team developing C++ code, please consider having one of your
  251. developers on a ``Usenet Sabbatical'' to extend this philosophy to C++, and
  252. start reaping the benefits in documentation time savings.
  253.  
  254. It could also make an ideal Computer Science student compiler project.
  255.  
  256. Please contact me via E-mail if you are interested in undertaking such a
  257. project.
  258.  
  259.  
  260. Graham Stoney
  261. greyham@research.canon.oz.au
  262.  
  263. Footnotes:
  264. 1. Advocates of Literate Programming would argue that Literate Programming is
  265.    much more than snazzy documents and that it encourages this extra effort to
  266.    focus early on in the design of the software, which pays off later.
  267.  
  268. 2. To get a better idea, see the file grammar.y in the c2man distribution.
  269.  
  270. 3. c2man has been posted to comp.sources.misc. It should be available from:
  271. location:    ftp from any comp.sources.misc archive, in volume42
  272.         (the version in the comp.sources.reviewed archive is obsolete)
  273.         ftp /pub/Unix/Util/c2man-2.0.*.tar.gz from dnpap.et.tudelft.nl
  274.     Australia:    ftp /usenet/comp.sources.misc/volume42/c2man-2.0/*
  275.         from archie.au
  276.     N.America:    ftp /usenet/comp.sources.misc/volume42/c2man-2.0/*
  277.         from ftp.wustl.edu
  278.     Europe:    ftp /News/comp.sources.misc/volume42/c2man-2.0/*
  279.         from ftp.irisa.fr
  280.     Japan:    ftp /pub/NetNews/comp.sources.misc/volume42/c2man-2.0/*
  281.         from ftp.iij.ad.jp
  282.     Patches:    ftp pub/netnews/sources.bugs/volume93/sep/c2man* from lth.se
  283.  
  284. 4. Jim Roskind's yaccable C++ grammar is available via ftp from
  285.    ics.uci.edu in the ftp/pub directory as:
  286.  
  287.         c++grammar2.0.tar.Z 
  288.         byacc1.8.tar.Z
  289.  
  290. 5. c2man's copyright requires that all derivative works remain freely
  291.    available.
  292.  
  293.